Tangible Software Solutions
Instant C# Help
Contents
- Project & Folder Conversion
- File & Snippet Conversion
- Command Line Conversion
- Code Formatting Options
- Conversion Message Options
- Custom String Replacements
- Diagnostic Options
- File Encoding Options
- Project Conversion Groups
- Default Shared Assemblies for Conversions
- Assumed Imported Namespaces for Snippet Conversions
- Project Conversion Options
- Enhancement Options
- Microsoft.VisualBasic Namespace Options
- Additions & Omissions
- Miscellaneous Options
- Assembly Resolution
Project & Folder Conversion
The Project & Folder Converter tab allows you to convert
all VB code within a project, solution, or folder. Once the conversion is finished, you can then
launch the new project or solution, view Instant C# comments, compare converted code files
to original code files, and view the new project or solution folder.
The folder conversion option allows you to convert all VB code within a folder hierarchy.
The Conversion History listview displays previously converted projects and allows you
to launch the project, view remaining Instant C# comments, and view the project folder.
File & Snippet Conversion
The File & Snippet Converter tab allows you to convert
VB code snippets or files. From the left side textbox, you can type or paste code
snippets, insert files, or view Instant C# sample snippets. Once a file or
snippet is converted, you can select and copy the results, save the results to a file,
or search the results.
Command Line Conversion
Instant C# can be launched from the command line with one or two parameters plus
an optional last parameter indicating the location of a conversion options file. If only one parameter is specified,
it is interpreted as the name of one of your custom project conversion groups. If two parameters are specified,
the first parameter is either a VB project file, solution file, folder, or file that you wish to convert,
and the second parameter is the folder or file that the converted C# project will be written to.
If the optional last parameter indicating the location of a conversion options file is included, then
that file is imported before the conversion starts. A conversion options file
has the extension '.opt' and is produced by exporting existing options to an xml file from the converter.
e.g. (project group conversion),
"Instant CSharp" "MyProjectGroup"
e.g. (single project conversion),
"Instant CSharp" "C:\VB Projects\Sample Project.vbproj" "C:\C# Projects\Sample Target Folder"
e.g. (solution conversion),
"Instant CSharp" "C:\VB Projects\Sample Solution.sln" "C:\C# Projects\Sample Target Folder"
e.g. (folder conversion),
"Instant CSharp" "C:\VB Projects\Sample Source Folder" "C:\C# Projects\Sample Target Folder"
e.g. (file conversion),
"Instant CSharp" "C:\VB Source Files\testfile.vb" "C:\C# Converted Files\testfile.cs"
e.g. (folder conversion with a conversion options file specified),
"Instant CSharp" "C:\VB Projects\Sample Source Folder" "C:\C# Projects\Sample Target Folder" "C:\Options\Instant C#.opt"
Once the command line conversion is complete, Instant C# will shut down.
Note that Instant CSharp must be in double quotes since the executable name contains a space.
- Braces: You can choose whether to place opening
braces on the next line after the construct header (default) or at the end of the same line.
You can choose whether to have braces vertically aligned with the construct (default) or
indented. Loops and if or else blocks with a single statement are converted by default
with enclosing braces. If you prefer to exclude braces for these cases then check
the preference to remove braces for single statement loops and if/else blocks.
- Indentation: You can choose whether the converted code uses
tabs or spaces for the leading white space. If you choose tabs for leading white space, then
leading spaces in the original code of the length that you specify are replaced by tabs. If you
choose spaces for leading white space, then tabs in the original code are replaced by spaces
of the length that you specify.
- Spacing: You can choose the degree to which
Instant C# inserts spaces in the converted code. By default, binary operators
are padded with spaces and control structures have a space inserted after the keyword,
but you can switch off this behavior or insert spaces in other situations.
- Control Statements: If you
select this option, the converter will break apart control structure statements
(if and while statements) by the main conditions. See the output in the
textbox to see the effect of this option.
- Method Declarations: If you select this
option, the converter will break apart method declarations by the method parameters. See the
output in the textbox to see the effect of this option.
- Method Calls: If you select this
option, the converter will break apart method calls by the method call arguments. See the
output in the textbox to see the effect of this option.
- String Literal Concatenation: If you select this
option, the converter will break apart multiple string literal concatenations to separate
lines. See the output in the textbox to see the effect of this option.
- Start LINQ queries on a new line: Selecting this
option causes Instant C# to format LINQ queries so that the starting from
appears on a new line.
- Break LINQ queries on keywords: Selecting this
option causes Instant C# to format LINQ queries so that the keywords where,
from, select, group, join, and orderby begin new lines.
Conversion Message Options
On this options dialog, you can customize the comment prefixes
that the converter uses for messages and also toggle the messages that Instant C#
displays on or off.
You can easily set all or none to display via the 'Select All' and 'Select None' buttons.
Custom String Replacements
Instant C# allows you to specify your own custom replacements
in the converted C# code. This can be useful for customizing code according to style
preferences that may be different in C# than in VB. It's also useful for cases where
a VisualBasic namespace method without a .NET equivalent will be replaced by your own
custom method to be called from the converted code.
For each replacement string you can specify the regex option, when to perform the replacement
(pre or post conversion), whether or not to match case, whether to match whole words only,
and whether comments or string literals should be modified. The whole words and string literals
options do not apply if the regex option is selected.
To span mulitple lines, either paste directly into the 'Find' and 'Replacement'
textboxes, or use the escaped characters: \r\n\t.
The "Active" checkbox can be unchecked if you wish to temporarily bypass the replacement.
Replacements are made in the order that they appear on the options dialog. For example,
the second replacement is made to each line of code after the first replacement has already
been made. To change the order of replacements, use the 'Up' and 'Down' buttons.
For an example of the regex option, you could do a custom replacement of "Foo(x)" with "Bar(x)",
where "x" is any argument, by specifying the "Find" field as "Foo(([\sa-zA-Z_$]*))" and the
"Replace" field as "Bar$1". Note that there are differences in various regex engines - the
regex engine used by the converter is .NET System.Text.RegularExpressions.Regex.
Diagnostic Options
These options are intended to provide information to
Tangible Software Solutions if a conversion is taking longer than expected.
'Record processing by file' instructs the converter to make a record of the files
processed and the time taken for each process. 'Record the last 100 lines of code
parsed before cancelling conversion' instructs the converter to make a record of the
most recent lines parsed before you cancelled the conversion.
File Encoding Options
The converter detects input file encoding from the byte order
mark (BOM), but if the BOM is missing the converter assumes by default that the file encoding
is UTF-8. You can use this option to specify a different default encoding to use in the absence
of a BOM. Output is written in the same encoding as the encoding detected for the original file,
or your default encoding option if the original coding was not detected via the BOM.
For UTF-8, you can choose whether or not to include the BOM for the output - this is normally
used in Windows environments.
Project Conversion Groups
If you need to regularly convert many projects at the same time,
use the Conversion Groups feature. This is most commonly used to convert sets of sample
projects to C#.
To configure Conversion Groups, go to Options->Project Conversion Groups on the main menu
or toolbar.
To convert a Conversion Group, go to Convert->Convert Group on the main menu.
Default Shared Assemblies for Conversions
For snippet and folder conversions, you can specify the
assemblies that the converter should resolve when interpreting the original code.
For .NET Core SDK projects, the project file contains no information about the shared
assemblies used by the project. The converter will not automatically attempt to resolve
every assembly in the .NET Core shared assembly location since it takes time to resolve the type
information in each assembly. Instead, we resolve only the shared assembly defining the core types
(System.Private.CoreLib) and allow you to select other assemblies for each project SDK that
you typically use.
For .NET Framework SDK projects, the project file contains no information about the GAC
assemblies used by the project. The converter will not automatically attempt to resolve
every assembly in the .NET Framework GAC assembly location since it takes time to resolve the type
information in each assembly. Instead, we resolve only the GAC assemblies 'mscorlib' and
'System' and allow you to select other assemblies for each project SDK that
you typically use.
Assumed Imported Namespaces for Snippet Conversions
You can specify namespaces that you would like the snippet converter
to assume are available when interpreting the original code. The snippet converter will then
convert as if the snippet contained the corresponding 'Imports' directives.
Project Conversion Options
- Bypass assembly resolution dialogs: By default,
Instant C# prompts you for the location of assembly dll's that it cannot find - this aids
in identifying the best conversion for some references to these assemblies. Also,
Instant C# will display message boxes if it cannot resolve the types or members within
an assembly. Select this option if you do not want to see these dialogs.
- Include a reference to the Microsoft.VisualBasic assembly:
By default, Instant C# includes a reference to the Microsoft.VisualBasic assembly
in the converted C# project to handle items that have no other .NET equivalent.
Uncheck this option if you never want a reference to this assembly. This option only applies to
.NET Framework projects (not .NET Core projects).
- Include the MyComputer.cs helper file: By default,
Instant C# includes a helper file named MyComputer.cs which handles some calls to
My.Computer. Uncheck this option if you never want this helper class included.
- Reproduce project integer overflow setting: By default,
Instant C# will reproduce the same integer overflow settings as the original VB project.
For VB projects, this is called 'RemoveIntegerChecks' and for C# projects, this is called
'CheckForOverflowUnderflow'. Since these are opposite in meaning, the values in the project
file are reversed. If you uncheck this option, the default C# behavior of not checking for
integer overflow will be in effect for the converted project.
- Conversion of VB project-level imports:
By default, Instant C# adds using statements corresponding to the VB Imports specified in the project file.
However, you also have the option to convert to C# 10 'Using Include' sections in the converted SDK project file or to ignore
the project-level imports.
- Warning level for converted C# projects: C# projects
have a warning level which can range between 0 and 4. Instant C# will set the warning
level of the converted project to this value.
Enhancement Options
These options relate to changes that correct or streamline
issues that existed in the original code, but are not required from a conversion or
formatting perspective. Most of these issues are more likely to appear in code migrated
from older versions of Visual Basic.
- Convert VB And/Or to C# &&/|| when the operands
are boolean values:
While AndAlso and OrElse are always converted to the C# && and
|| operators, the strict equivalent of VB's And and Or operators are the
C# bitwise & and | operators, which are also overloaded to serve as non-short-circuiting
logical operators. However, when the operands are confirmed to be boolean values,
Instant C# converts these to the short-circuiting && and || operators.
One case that is not converted to short-circuiting operators is the case where
the right-hand side of the expression is a function call - this is done to preserve
side-effects of the function call. If you prefer to always convert VB's
non-short-circuiting operators to non-short-circuiting operators in C#,
then uncheck this preference.
- Move initialization to variable declaration if immediately following the declaration:
By default, Instant C# will add a variable initialization to the variable declaration
if the initialization is on the line following the declaration.
- Detect unused local variables: If you select this
option, Instant C# will either comment or remove local variables that are
unreferenced later in the local method scope. However, the variable will remain
if it is initialized to an expression which may have side-effects (e.g., a method call
or an instantiation of a type).
- Change the type of local object variables to match the type of the initializer:
If you select this option, Instant C# will change object variable types to the type
of the initializer, if the variable is declared with an initializer.
Microsoft.VisualBasic Namespace Options
By default, Instant C# converts many Microsoft.VisualBasic
namespace members with calls to intrinsic .NET methods. This includes many string
and date functions which have a close equivalent in .NET.
Other members which have no close equivalent are left as calls to the
Microsoft.VisualBasic namespace (which will still function in C#). Since the
.NET string and date equivalents may not be exact (especially in the treatment
of null values), you have the option of not converting some of these calls and
using the Microsoft.VisualBasic namespace in the converted code.
- VisualBasic.Strings:
Many VisualBasic.Strings methods are converted to their very close .NET equivalents,
but you can choose to leave the original VB namespace calls in the converted output.
- VisualBasic.DateAndTime:
Many VisualBasic.DateAndTime members are converted to their very close .NET equivalents,
but you can choose to leave the original VB namespace calls in the converted
output.
- Other:
- Convert VB IsNumeric using a helper method: The VB
IsNumeric function is converted using a helper method inserted by Instant C#,
but you can choose to leave the original VB namespace calls in the converted output.
- Convert VB IsDate using a helper method: The VB
IsDate function is converted using a helper method inserted by Instant C#,
but you can choose to leave the original VB namespace calls in the converted output.
- Convert VB Val using a helper method: The VB
Val function is converted using a helper method inserted by Instant C#,
but you can choose to leave the original VB namespace calls in the converted output.
- Conversion of Constants.vbCrLf and ControlChars.CrLf:
You have the option of converting the VB constants Constants.vbCrLf and
ControlChars.CrLf to either "\r\n" (exactly equivalent) or Environment.NewLine
(not always equivalent, but sometimes preferred). Other VB constants are converted to
the natural C# equivalent.
Additions & Omissions
- Add to the top of all converted files: If you add text
for this option, that text will be added to the top of every converted file. This option
does not apply to code snippet conversions.
- Omit code regions for these preprocessor tokens:
Instant C# will remove regions of code from the conversion output which are in
preprocessor blocks positively conditional on any of these tokens (e.g., #If OMIT Then).
- Copy code unconverted for these preprocessor tokens:
Instant C# will leave regions of code unconverted which are in preprocessor blocks
positively conditional on any of these tokens (e.g., #If COPY Then).
Any #ElseIf or #Else blocks following the #If section are removed from the conversion
output.
Miscellaneous Options
- Renaming tag for code element conflicts: Instant C#
must occasionally rename class members to avoid conflicts. You can choose your own
renaming tag and whether to place it at the beginning or end of the original name
when this is necessary.
- Nullable type syntax: To specify nullable types,
you can either use the shorter syntax using the ? nullable token or the longer syntax
which explicitly states the type, such as Nullable<bool>. Instant C#
converts to the shorter syntax by default.
- Suppress case adjustments: Although VB is
case-insensitive, newer versions of Visual Studio do a very good job of automatically
adjusting the case of member names. Check this preference if you would prefer not
to have Instant C# perform case-adjustment heuristics.
- Use postfix operator where possible:
You have the option of converting unitary increment/decrement statements such
as i = i + 1 or i += 1 to the very concise C# postfix form i++.
- Insert temporary variables for 'For' loop ending conditions that are not constant:
VB evaluates the ending condition of For loops exactly once, while C# evaluates
it on every iteration. If Instant C# determines that it is possible that the ending
condition may change, then it inserts a temporary variable set to the original ending
condition and uses that temporary variable in the C# for loop.
- Always convert to explicit interface implementation:
C# has two styles for implementing interface methods: implicit (methods are matched
by name and parameters) or explicit (the method name is qualified by the interface name).
Instant C# uses the implicit method by default for public methods since it maintains the
original VB intent better (for non-public methods, the explicit interface implementation
is always used to reproduce the same behavior).
- Suppress insertion of type casts or conversions:
By default, Instant C# will insert type casts or conversions to replicate the behavior
of VB implicit casting. If you want to avoid having any type casts or conversions
inserted by the converter, then choose this option.
- Convert strings with escaped characters to verbatim strings:
By default, Instant C# uses the escape character for strings containing the double quote
or backslash character, but this option changes these to verbatim strings. (VB 2015
multiline strings are always converted to C# verbatim strings).
- Assume 'Option Strict On' for snippets if no 'Option Strict' statement found:
By default, the converter assumes 'Option Strict Off' for snippet conversions if no
'Option Strict' statement is found.
- Assume 'Option Infer On' for snippets if no 'Option Infer' statement found:
By default, the converter assumes 'Option Infer On' for snippet conversions if no
'Option Infer' statement is found.
- Convert VB numeric casts using helper class methods:
By default, Instant C# will convert VB numeric casts (such as CInt) to
System.Convert method calls. If you want to replicate the exact behavior of the VB
numeric casts, which accept the thousands separator, parentheses, currency symbols,
and trailing sign characters, then choose this option. This option doesn't apply to
casts from integer types to numeric types or to casts from floating point types to
numeric types - for these cases, either a regular C# cast or a call to a System.Convert
method will always be sufficient.
- Use strict conversions of VB string comparisons:
By default, Instant C# will convert string comparisons to C# comparisons which are very
similar syntactically ('=' to '==' and '<>' to '!='). However, if you want to replicate
the exact behavior of VB string comparisons, which interpret null strings as empty strings,
then choose this option.
- Use target-typed new in field and local variable declarations:
If you choose this option, the converter will convert local variable and field declarations to use
'target-typed new' syntax (e.g., Foo<Bar> fooBar = new Foo<Bar>() becomes Foo<Bar> fooBar = new()).
- Perform strict conversion of WithEvents & Handles:
In VB, the Handles clause on methods causes the method to be automatically wired
to the WithEvents field's events in the Handles clause. Instant C# converts
these by default to simple event wireups if the WithEvents fields are initialized
in an InitializeComponent method or if the events belong to the current class.
For other cases, Instant C# transforms the related WithEvents fields
to properties which perform the event wireups when the WithEvents variable
is set. You have the option to apply strict conversion to WithEvents fields
which are initialized in an InitializeComponent method, but this will mean that
the events will not show in the designer view. You also have the option to include
designer file WithEvents fields - these are excluded by default since many
designer tools cannot handle changes made to the designer file or may lose the changes.
If you don't choose the strict conversion option, then all event wireups that don't
belong in InitializeComponent are set in a constructor.
Assembly Resolution
Assemblies referenced by projects are examined to
determine the nature of the types and members within the assembly to improve the conversion
quality.
During the project conversion process you may be prompted
by the converter to find specific assemblies referenced by your project if they
cannot otherwise be found by the converter.
If the converter does not resolve all assemblies, you can still
continue the project conversion, but the conversion may not be optimal for code which
references the unresolved assemblies. This just means that a few more manual adjustments
may be required.
If the assembly does not require an install, you can forward it
to us in a zip file to determine why it is not resolving.
Copyright © Tangible Software Solutions, Inc.